Mac Magazin/MacEasy 14

home *** CD-ROM | disk | FTP | other *** search

/ Mac Magazin/MacEasy 14 / Mac Magazin and MacEasy Magazine CD - Issue 14.iso / Wissenschaft & Technik / Tools Plus 2.6.1 Evaluation Kit / Tools Plus 2.6.1 / User Manual / 14-System Polling (2 of 4) < prev next >

Wrap

INI File | 1994-09-17 | 30KB | 456 lines

[Display using Monaco 9] Event Modifiers ``````````````` Tools Plus’s event modifier field provides information identical to that obtained directly from the Macintosh’s Event Manager. To reiterate, the Modifiers field of the event record contains information about the position of the Caps Lock, Shift, Option, Command and Control keys at the time of the event, as well as the position of the mouse button. This can be used, for example, to detect if the Command key was down when a key was typed (i.e. a Command-key sequence). In effect, your application could respond to command key sequences that are not menu equivalents by using this method. Your application could also place special significance on Option-Clicks. The most common use, however, is Shift-Tab that indicates that the user wants to tab to the previous field. In the Macintosh’s Event Manager, the Modifiers field of the event record is an integer. Several of the bits indicate the state of the various modifiers, as detailed in Inside Macintosh Vol 1 and Vol 5. Tools Plus goes a step further and automatically decodes individual modifiers in the field. This is handled through a union in C, and a variant record in Pascal. Event Modifiers Using C ``````````````````````` When programming in C, Tools Plus’s Modifiers structure is a union that lets you access both the integer obtained from the Macintosh’s Event Manager, as well as the individual flags (bits) within the integer. Tools Plus’s Modifiers structure looks like this: union TPModifiersRec { /*This variable record contains */ /* an event's "modifiers" in 2 */ /* formats… */ /* • Macintosh Event: */ short Num; /* integer (bit operations */ /* required) */ /* • Modifier integer parsed */ struct { /* into components: */ unsigned short bit15 :1; /* (reserved bit) */ unsigned short bit14 :1; /* (reserved bit) */ unsigned short bit13 :1; /* (reserved bit) */ unsigned short ControlKey :1; /* Control key was down at event */ unsigned short OptionKey :1; /* Option key was down at event */ unsigned short CapsLock :1; /* Caps Lock was down at event */ unsigned short ShiftKey :1; /* Shift key was down at event */ unsigned short CmdKey :1; /* Command key was down at event */ unsigned short MouseUp :1; /* Mouse button was UP at event */ unsigned short bit6 :1; /* (reserved bit) */ unsigned short bit5 :1; /* (reserved bit) */ unsigned short bit4 :1; /* (reserved bit) */ unsigned short bit3 :1; /* (reserved bit) */ unsigned short bit2 :1; /* (reserved bit) */ unsigned short bit1 :1; /* (reserved bit) */ unsigned short bit0 :1; /* (reserved bit) */ } Bits; /* */ }; typedef union TPModifiersRec TPModifiersRec; Whenever you access any of the individual modifier flags, you reference the “bits” part of the structure. For example, if you want to check if the Command key was down and the Option key was up when a key was typed, you can use an expression such as this: if ((Poll.Modifiers.Bits.CmdKey) && (!Poll.Modifiers.Bits.OptionKey)) In contrast, the Modifiers field provided by the Macintosh’s Event Manager requires bitwise “And” operations to determine if a bit is set or not, thereby resulting in source code that looks more cryptic. The following line duplicates the previous example’s functionality using bitwise “And” operations instead of the available bits: if ((Poll.Modifiers.Num & cmdKey) && !(Poll.Modifiers.Num & optionKey)) When you are working with the Modifiers structure, you may perform operations exclusively on the integer variant of the structure, on the bits variant, or if you choose, you can mix and match as needed. Several constants representing the “bit-equivalents” for the various flags contained in the Modifiers integer are available as follows: /*Modifier masks */ #define btnState 0x0080 /*set to 1 if mouse button is up */ #define cmdKey 0x0100 /*set to 1 if Command key is down */ #define shiftKey 0x0200 /*set to 1 if Shift key is down */ #define alphaLock 0x0400 /*set to 1 if the Caps Lock key is down */ #define optionKey 0x0800 /*set to 1 if the option key is down */ #define controlKey 0x1000 /*set to 1 if the control key is down */ Event Modifiers Using Pascal ```````````````````````````` When programming in Pascal, Tools Plus’s Modifiers structure is a variant record that lets you access both the integer obtained from the Macintosh’s Event Manager, as well as the individual flags (bits) within the integer. Tools Plus’s Modifiers record looks like this: {= Polling record's "event modifiers" info} TPModifiersRec = packed record {This variable record contains } { an event's "modifiers" in 2 } case integer of { formats… } 0: ( { • Macintosh Event: } Num: integer { integer (bit operations } ); { required) } 1: ( { • Modifier integer parsed } { into components: } bit15, bit14, bit13: boolean; { (reserved bits) } ControlKey: boolean; { Control key was down at event } OptionKey: boolean; { Option key was down at event } CapsLock: boolean; { Caps Lock was down at event } ShiftKey: boolean; { Shift key was down at event } CmdKey: boolean; { Command key was down at event } MouseUp: boolean; { Mouse button was UP at event } bit6, bit5, bit4, bit3, bit2, { (reserved bits) } bit1,bit0: boolean; { } ); { } end; You use each field in the record as an individual modifier variable. For example, if you want to check if the Command key was down and the Option key was up when a key was typed, you can use an expression such as this: if Poll.Modifiers.CmdKey and not Poll.Modifiers.OptionKey then In contrast, the Modifiers field provided by the Macintosh’s Event Manager requires bitwise “And” operations to determine if a bit is set or not, thereby resulting in source code that looks more cryptic. The following line duplicates the previous example’s functionality using bitwise “And” operations instead of the available bits: if (BitAnd(Poll.Modifiers.Num,cmdKey) <> 0) and BitAnd(Poll.Modifiers.Num,optionKey) = 0) then When you are working with the Modifiers record, you may perform operations exclusively on the integer variant of the record, on the bits variant, or if you choose, you can mix and match as needed. Several constants representing the “bit-equivalents” for the various flags contained in the Modifiers integer are available as follows: CONST {Modifier masks } btnState =$0080; {set to 1 if mouse button is up } cmdKey =$0100; {set to 1 if Command key is down } shiftKey =$0200; {set to 1 if Shift key is down } alphaLock =$0400; {set to 1 if the Caps Lock key is down } optionKey =$0800; {set to 1 if the option key is down } controlKey=$1000; {set to 1 if the control key is down } ------------------------------------------------------------------------ PollSystem `````````` Determine if an event occurred, and obtain that event. PollSystem also keeps Tools Plus’s automatic processes running. pascal Boolean PollSystem (TPPollRecord *Poll); function PollSystem(var Poll:TPPollRecord): BOOLEAN; The Poll record contains all the information about an event. The function’s value returns true if an event was obtained, and false if an event was not obtained. When PollSystem returns false, it is called a “null” event, or in Tools Plus terminology, a doNothing event. PollSystem calls the Macintosh Event Manager’s WaitNextEvent function (or GetNextEvent function) which performs all necessary task switching and background processing control. Desk Accessories’ get their events, and other applications that are also running under MultiFinder or System 7 get some processing time. If your application does “background processing,” that is, it performs an on-going process while it is waiting for events, it should perform “one cycle” of its background process each time it receives a doNothing event (when PollSystem returns false). A single cycle of your application’s background process should take no longer than 1/60 of a second. See the SetNullTime routine to set the interval at which your application receives doNothing events. PollSystem should be called as often as possible (at least sixty times per second) to keep desk accessories, automatic processes, and other applications running under MultiFinder or System 7 running smoothly. It is important that your application does not do a lot of processing between calls to PollSystem or it will be a “CPU hog” and make other applications run sluggishly or in spurts and jumps. Also see: SetNullTime. Note: Your application should call PollSystem as often as possible (at least 60 times per second) to allow other applications adequate processing time. Warning: Do not call PollSystem from within a BeginUpdateScreen / EndUpdateScreen structure. Tools Plus Event Codes `````````````````````` Each event reported by PollSystem is identified by the first field of the polling record, Poll.What. The Poll.What field contains an event code that tells your application what to do with the event record’s information. Constants are used to identify event codes as follows: CONST {Tools Plus event codes } doNothing = 0; {no event } doChgWindow = 1; {user clicked in an inactive window } doRefresh = 2; {a window has to be refreshed } doGoAway = 3; {the Go-Away box was clicked } doButton = 4; {button was clicked } doMenu = 5; {menu was selected } doKeyDown = 6; {a keyboard key was pressed } doAutoKey = 7; {a keyboard key is auto-repeating } doKeyUp = 8; {a keyboard key was released } doClickField = 9; {mouse clicked in inactive editing field} doScrollBar = 10; {mouse clicked in a scroll bar } doListBox = 11; {some sort of List Box activity } doClick = 12; {mouse click/drag [1..3] } doPopUpMenu = 13; {pop-up menu was selected } doPictButton = 14; {picture button activity } doClickControl=101; {mouse clicked in a custom control } doManualEvent =102; {manually processed events } doMoveWindow =103; {a window was moved by user } doGrowWindow =104; {a window was “grown” by user } doClickDesk =105; {mouse clicked in the desk top } doZoomWindow =106; {zoom box was clicked by user } doSuspend =107; {appl. suspended (in background) } doResume =108; {appl. resumed (now active appl.) } doChgInField =109; {contents of active field was changed } doPreRefresh =110; {a window may be refreshed (before Tools} { Plus objects are drawn) } Event codes over 100 will likely be ignored by most applications. All events are detailed later, telling you how to respond to the event and which fields in the event record contain valid information that is related to the event. What Does PollSystem Do? ```````````````````````` On the surface, it appears that PollSystem is just a fancy way to get an event from the Toolbox Event Manager. Quite to the contrary, PollSystem does a lot of work for you. The biggest service that PollSystem performs is to keep Tools Plus’s automatic processes running smoothly. To do this, you must understand the difference between an internally processed event, and an externally processed event. Internally Processed Events ``````````````````````````` An internal event is something that can be processed by Tools Plus without the knowledge or assistance of your application. Hence the term internal means internal to Tools Plus. The internal processing of events is how PollSystem drives its automatic tasks. An example of an internally processed event is a key-down event from the Toolbox Event Manager. If the active window belongs to your application and it has an active editing field, the user’s key-strokes are automatically applied to the active field thereby affecting the text in the editing field. Since the key-down event is processed internally, it is not reported to your application. Externally Processed Events ``````````````````````````` Whenever PollSystem encounters an event it cannot process internally, it reports the event to your application. An example of this is when the user clicks the close box in the active window. Your application may want to ask the user if he wants to save the changes before closing the document. Therefore, PollSystem only reports a request to close a window, and does not actually close it. Some events may be ignored by your application. One of these events tells your application that the user dragged a window. Your application may be interested in a window’s co-ordinates at any given time, in which case this event would be crucial. In most cases, applications don’t care if the window is dragged, and always ignore that event. Inside PollSystem ````````````````` Inside PollSystem describes the inner workings of the PollSystem routine. Those programmers who are curious about this aspect, or those that want to know how Toolbox Events are translated into Tools Plus events may find this passage interesting. Every time your application calls PollSystem, several things happen automatically: (1) Desk accessories and background processes are given some processing time. (2) The active desk accessory (if there is one) gets any events it requires. (3) The insertion point is kept blinking in the active editing field (if there is one). (4) Task switching occurs to give other applications some processing time (when using MultiFinder or System 7). (5) The event queue is checked for an event. If any events exist, the first one is removed from the queue. If the event can be processed internally by Tools Plus, it is and this step is repeated. (6) If an event is obtained that can not be processed internally by Tools Plus, then Tools Plus’s event record is populated with all the required information for that event in a format that is readily usable by your application. (7) The cursor’s position is checked and its shape is changed if required. (8) PollSystem returns to your application with an event, or a “no event” (false) status. Translating Toolbox events to Tools Plus events ``````````````````````````````````````````````` Step 3 looks pretty simple when it is summarized in a couple lines, however, the recognition and processing of internal events is quite an extensive duty for Tools Plus. The table below describes this formidable task by listing the Macintosh’s Toolbox Event Manager’s event, the internal processes that follow, and the event that finally reaches your application. Remember that some Toolbox events are processed internally and never reach your application, and some events that reach your program can be ignored. ============+=========================================+=============== Toolbox’s | Conditions and | PollSystem’s Event | Tools Plus’s Internal Processing | Event ============+=========================================+=============== nullEvent | none | doNothing ------------+-----------------------------------------+--------------- mouseDown | If the watch cursor is displayed then | | the event is ignored (clicks in push | | buttons are optionally exempted) | |-----------------------------------------+--------------- | Outside of a modal window (beep) | |-----------------------------------------+--------------- | In an inactive window that belongs to | doChgWindow | your application | |-----------------------------------------+--------------- | In a floating palette that is not the | doPreRefresh | front most palette, and is partially | doRefresh | obscured by another palette. After | | refreshing the window, the mouse-down | | event is processed. | |-----------------------------------------+--------------- | In a floating palette’s title bar | |-----------------------------------------+--------------- | In an inactive window that belongs to | doSuspend | another application or desk accessory | |-----------------------------------------+--------------- | In Apple menu, except for “About…” item | | (selected item is opened or activated) | |-----------------------------------------+--------------- | In Apple menu’s “About…” item | doMenu |-----------------------------------------+--------------- | Edit menu’s Undo/Redo, Cut, Paste, or | doChgInField | Clear item is selected for an active | | editing field in your application. | | Operation is done automatically. Your | | application is informed of the change | |-----------------------------------------+--------------- | Edit menu’s Copy item is selected for | | an active editing field in your | | application (operation is done | | automatically) | |-----------------------------------------+--------------- | Edit menu’s Undo, Cut, Copy, Paste, or | | Clear item is selected for a desk | | accessory (operation is done | | automatically) | |-----------------------------------------+--------------- | In other (pull-down or hierarchical) | doMenu | menu selection | |-----------------------------------------+--------------- | In a pop-up menu | doPopUpMenu |-----------------------------------------+--------------- | In an active desk accessory or other | | application (clicking, dragging, or | | closing, etc.) | |-----------------------------------------+--------------- | Selecting or deselecting lines in a | doListBox | list box. | |-----------------------------------------+--------------- | Button in the active window (only if | doButton | mouse was released inside the button’s | | area) | |-----------------------------------------+--------------- | Picture button in the active window: | doPictButton | buttons with the “repeating events” | | option turned on produce events while | | the picture button is held down, as long| | as the button does not reach the end of | | its range. Those without the “repeating| | events” option produce an event only if | | mouse was released inside the button’s | | area. | |-----------------------------------------+--------------- | Scroll bar in the active window (while | doScrollBar | in up arrow, down arrow, Page up region,| | or Page Down region, or if thumb was | | moved) | |-----------------------------------------+--------------- | Active editing field, when setting a | | new insertion point or selection range | | (Edit menu’s items are enabled/disabled | | according to the insertion point or | | selection) | |-----------------------------------------+--------------- | Inactive editing field | doClickField |-----------------------------------------+--------------- | Single-click, double-click, triple- | doClick | click, and/or dragging | |-----------------------------------------+--------------- | Active window is dragged by user | doMoveWindow |-----------------------------------------+--------------- | Active window’s size is changed by | doGrowWindow | using the size box | |-----------------------------------------+--------------- | Active window’s close box was clicked | doGoAway |-----------------------------------------+--------------- | Active window’s “zoom box” was clicked | doZoomWindow |-----------------------------------------+--------------- | Custom control | doClickControl |-----------------------------------------+--------------- | On the desk top | doClickDesk ------------+-----------------------------------------+--------------- mouseUp | none | ------------+-----------------------------------------+--------------- keyDown | If the watch cursor is displayed then | autoKey | the event is ignored (except for | | Command-.) | |-----------------------------------------+--------------- | Command key invoking Edit menu’s | doChgInField | Undo/Redo, Cut, or Paste item in an | | active field in your application. | | Operation is done automatically. Your | | application is informed of the change. | |-----------------------------------------+--------------- | Command key invoking Edit menu’s Copy | | item is selected for an active editing | | field in your application (operation is | | done automatically) | |-----------------------------------------+--------------- | Command key invoking Edit menu’s Undo, | | Cut, Copy, or Paste item in an active | | desk accessory under Finder (the editing| | operation is done automatically) | |-----------------------------------------+--------------- | Command key invoking a menu | doMenu |-----------------------------------------+--------------- | Command key NOT invoking a menu | doKeyDown or | | doAutoKey |-----------------------------------------+--------------- | Enter or Return key invoking a default | doButton | push-button | |-----------------------------------------+--------------- | Active editing field processing keys | | (Edit menu’s items are enabled/disabled | | according to the selection in the | | editing field. Undo item is changed | | according to field’s contents, such as | | “Undo Typing”) | |-----------------------------------------+--------------- | Other key strokes | doKeyDown or | | doAutoKey ------------+-----------------------------------------+--------------- keyUp | If the watch cursor is displayed then | | the event is ignored | |-----------------------------------------+--------------- | Active editing field ignores key up | | events | |-----------------------------------------+--------------- | Other key-ups, providing that | doKeyUp | SetEventMask has not masked out key up | | events | ------------+-----------------------------------------+--------------- updateEvt | A doPreRefresh event is reported first. | doPreRefresh | The next time PollSystem is called, | doRefresh | buttons, picture buttons, scroll bars, | | custom controls, editing fields, list | | boxes and pop-up menus are automatically| | redrawn (refreshed) and a doRefresh | | event is reported. This occurs whenever | | a partially obscured window becomes | | uncovered. | ------------+-----------------------------------------+--------------- activateEvt | When a window is deactivated, the | | following happens automatically: | | [1] text in the active editing field is | | deselected and the insertion point is | | removed, [2] list box lines are | | deselected, [3] scroll bars are hidden, | | [4] buttons and picture buttons are | | disabled, [5] pop-up menus are disabled,| | and [6] if the window has a “grow box,” | | it is hidden. When the window is | | activated again, all objects return to | | their normal state.. | ------------+-----------------------------------------+--------------- diskEvt | no internal processing | doManualEvent networkEvt | | driverEvt | | app1Evt | | app2Evt | | app3Evt | | kHighLevel- | | Evt | | ------------+-----------------------------------------+--------------- app4Evt | If your application’s SIZE resource is | doManualEvent osEvt | set to not respond to Suspend/Resume | | events, then no internal processing | | occurs. | |-----------------------------------------+--------------- | If your application’s SIZE resource is | doSuspend or | set to respond to Suspend/Resume events,| doResume | then these event are reported to your | | application. In System 7, the osEvt | | representing the “mouse moved” event. | |-----------------------------------------+--------------- | In System 7 the osEvt also carries the | | “mouse moved” status, thereby becoming a| | “mouse moved event.” Tools Plus uses | | these events to automatically change the| | cursor’s shape. | ---------------------------------------------------------------------- Responding to Events ```````````````````` When PollSystem returns with a value of false, it indicates that no event has occurred. This is commonly called a “null event” or a doNothing event in Tools Plus. Usually, your application won’t do anything other than idle in the main event loop. Applications that do on-going processing should do their work only when they receive a null event. PollSystem returns with a value of true when an event is available. The first field in the polling record is “what,” which tells your application what type of event has occurred. The following section of this chapter describes how your application should respond to each event. It also details any programming considerations that should be taken into account when responding to such an event.